Expand description

Compare IEEE floating point primitives, structs and collections for equality.

This is API reference documentation. For introductory material, guides and discussion see the float_eq guide.

Basic usage

This crate provides boolean comparisons via float_eq! and float_ne!:

use float_eq::float_eq;

if (float_eq!(y_pos, 0.0, abs <= 0.000_1)) {
   //...
}

And asserts via assert_float_eq! and assert_float_ne!:

use float_eq::assert_float_eq;

const TOL: f32 = 0.000_366_210_94;
assert_float_eq!(0.1f32.recip(), 10.0, r2nd <= TOL);

Each of which invokes a specific comparison algorithm with an explictly provided toelrance. In these examples:

  • abs <= 0.000_1 is an absolute tolerance comparison with a tolerance of 0.000_1.
  • r2nd <= TOL is a relative tolerance comparison with a tolerance of TOL, scaled to the precision of the second operand.

Comparison algorithms

These are always of the form CHECK <= tol, where CHECK is one of:

When comparing homogeneous composite types that implement FloatEqAll, variants that use a uniform tol across all fields are also available:

Note: rel and rel_all are legacy aliases for rmax and rmax_all, but using the more precise algorithm names is recommended.

Combining checks

If multiple checks are specified in either a boolean comparison or an assert, they are applied left to right and will shortcut on success. For example:

float_eq!(a, b, abs <= abs_tol, ulps <= ulps_tol)

Is equivalent to:

float_eq!(a, b, abs <= abs_tol) || float_eq!(a, b, ulps <= ulps_tol)

Extending float_eq over custom types

See How to compare custom types.

Macros

Asserts that two floating point expressions are equal to each other.
Asserts that two floating point expressions are not equal to each other.
Asserts that two floating point expressions are equal to each other.
Asserts that two floating point expressions are not equal to each other.
Checks if two floating point expressions are equal to each other.
Checks if two floating point expressions are not equal to each other.

Structs

The absolute difference between two floating point num::Complex<T> instances in ULPs.

Traits

Debug context for when an assert fails.
Debug context for when an assert using an all check fails.
Compare IEEE floating point values for equality using per-field tolerances.
Compare IEEE floating point values for equality using a uniform tolerance.
Per-field results of ULPs based diff calculations.
Per-field tolerances for ULPs comparisons.

Type Definitions

Per-field results of ULPs based diff calculations.
Per-field tolerances for ULPs comparisons.

Attribute Macros

Helper for deriving the various float_eq traits.